Blakod Coding Standard

By: Brian Green Date: August 10, 2004

Purpose:

The purpose of this document is provide a coding standard for the Blakod scripting language.

Line Length

All text should be formatted to be readable at 80 column width. Any text that goes beyond this length should be reformatted to be fit on a new line.

Indentation

Indentation should use spaces instead of tabs. Indentation should be three spaces.

Indentation should be used to indicate scope and association.

Statements

There should only be one statement per line. Putting multiple statements on a single line should be avoided.

Statements that are broken up due to line length should be logical and properly indented. Operators should be place at the beginning of a new line.

Examples:

% One statement per line
a = a + 1;
b = b + 2;

% If statement on multiple lines
if oObject <> $
   AND Send(oObject,@IsActive)
{
   % something
}

% Multi-line math assignment
iVeryLongVariableName = Send(oObject,@VeryLongClassName,#parameter=ALongParameterName)
                        + Send(oObject,@OtherVeryLongClassName,#parm=AnotherLongName);

Capitalization and Naming

All script keywords, such as 'if', should be entirely in lower case.

All names in the script should be descriptive. Names should contain no spaces and each word should begin with a capital letter.

Example:

MyScriptName

The exception to this rule is for constants, as explained below.

In addition, operators that are words should be in all capitals. This includes boolean operators like AND, OR, NOT, and the mathematical operator MOD.

Constants

Constants are labelled in all capital letters, with underscores instead of spaces. Constants include all the values in blakston.khd, including the values for TRUE and FALSE.

Example:

A_CONSTANT_VALUE_NAME = 100

Variables

Although variables are not restricted by type, it is a good idea to indicate the expected type of the variable. This helps with debugging on the servers.

All variables of a class are of the format: <class function><type>VariableName
<class function> = nothing for local variables, 'v' for classvars, 'p' for properties.
<type> = 'b' for boolean, 'i' for integer, 'o' for object, 'l' for list, 't' for timer, 'r' for resource, 's' for string, 'h' for hash table, 'c' for class.

Examples:

% An integer classvar
viInitialValue

% A object property
poSomethingElse

% A local timer
tDeadlineTimer

Parameters

The following table show some default parameter names and their usual meaning.

who	Object of the message. Who is taking the action?
what	Direct object of the message. What is being acted upon?
lTargets	List of direct objects.

Spacing and Braces

Blank lines should be placed between logical blocks in the code. Putting a blank line before a comment makes it easier to pick out.

There should be a blank line after any closing brace, except in the case of an else statement for readability. There should also be a blank line before any statement which changes the flow, such as return, propagate, break, and continue statements.

Open and close braces for code blocks ( { and } ) should be placed on a new line separate from other code in the same column as the line before the block. All code between the braces should be indented to show scope of the code.

Example:

if x > 1
{
   x = x + 1;
   y = x - 1;
}

Return Values

Return values should be of a consistent type. Return boolean types (TRUE or FALSE) for tests. Return $ (nil) if you do not have anything to return. Mixing types (returning an object or FALSE if there is no object) should be avoided.